---
type: integration
title: '@astrojs/netlify'
description: 了解如何使用 @astrojs/netlify SSR 适配器来部署 Astro 项目。
githubIntegrationURL: 'https://github.com/withastro/adapters/tree/main/packages/netlify/'
category: adapter
i18nReady: true
---
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'

此适配器可以部署你的 [`hybrid` 或 `server` 渲染站点](/zh-cn/basics/rendering-modes/#按需渲染) 到 [Netlify](https://www.netlify.com/)。

如果你正在使用 Astro 作为[静态站点生成器](/zh-cn/basics/rendering-modes/#预渲染)，则不需要适配器。

在我们的 [Netlify 部署指南](/zh-cn/guides/deploy/netlify/) 中学习如何部署你的 Astro 网站。

## 为什么是 Astro Netlify

[Netlify](https://www.netlify.com/) 是一个部署平台，允许你通过直接连接 GitHub 仓库来托管你的网站。这个适配器增强了 Astro 的构建流程，为通过 Netlify 部署项目做好准备。

## 安装

Astro 包含了一个 `astro add` 命令，用于自动设置官方集成。如果你愿意，可以改为[手动安装集成](#手动安装)。

在 Astro 项目中使用以下 `asrto add` 命令添加 Netlify 适配器，以启用 SSR。这将安装 `@astrojs/netlify` 并一步到位地对你的 `astro.config.mjs` 文件进行相应的更改。

<PackageManagerTabs>
  <Fragment slot="npm">
  ```sh
  npm run astro add netlify
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```sh
  pnpm astro add netlify
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```sh
  yarn astro add netlify
  ```
  </Fragment>
</PackageManagerTabs>

### 手动安装

首先，使用适合你的包管理器将 Netlify 适配器安装到你的项目依赖中：

<PackageManagerTabs>
  <Fragment slot="npm">
  ```sh
  npm install @astrojs/netlify
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```sh
  pnpm add @astrojs/netlify
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```sh
  yarn add @astrojs/netlify
  ```
  </Fragment>
</PackageManagerTabs>

然后，将适配器和你所需的[按需渲染模式](/zh-cn/basics/rendering-modes/#按需渲染)添加到你的 `astro.config.*` 文件中：

   ```js title="astro.config.mjs" ins={2, 6-7}
    import { defineConfig } from 'astro/config';
    import netlify from '@astrojs/netlify';

    export default defineConfig({
       // ...
       output: 'server',
       adapter: netlify(),
    });
   ```

## 用法

[阅读完整的部署指南](/zh-cn/guides/deploy/netlify/)

按照指南 [在本地构建你的站点](/zh-cn/guides/deploy/#在本地构建站点)。构建完成后，你将会有一个包含 [Netlify Functions](https://docs.netlify.com/functions/overview/) 的 `.netlify/` 文件夹，其中包含 `.netlify/functions-internal/` 文件夹中的函数和 `.netlify/edge-functions/` 文件夹中的 [Netlify Edge Functions](https://docs.netlify.com/edge-functions/overview/)。

要部署你的站点，请安装 [Netlify CLI](https://docs.netlify.com/cli/get-started/) 并运行：

```sh
netlify deploy
```

这篇 [Netlify 博客文章](https://www.netlify.com/blog/how-to-deploy-astro/) 和 [Netlify 文档](https://docs.netlify.com/integrations/frameworks/astro/) 提供了更多关于如何使用这个集成部署到 Netlify 的信息。

### 从你的站点访问 edge 上下文

Netlify Edge Functions 提供了一个 [context 对象](https://docs.netlify.com/edge-functions/api/#netlify-specific-context-object)，其中包含有关请求的元数据，例如用户的 IP、地理位置数据和 cookie。

这可以通过 `Astro.locals.netlify.context` 对象访问：

```astro
---
const {
  geo: { city },
} = Astro.locals.netlify.context;
---

<h1>你好，来自{city}的友好访客！</h1>
```

如果你使用 TypeScript，你可以通过更新 `src/env.d.ts` 来使用 `NetlifyLocals` 来获得正确的类型：

```ts title="src/env.d.ts"
/// <reference path="../.astro/types.d.ts" />
/// <reference types="astro/client" />

type NetlifyLocals = import('@astrojs/netlify').NetlifyLocals

declare namespace App {
  interface Locals extends NetlifyLocals {
    // ...
  }
}
```

这不适用于预渲染的页面。

### 在 Netlify Edge Functions 上运行 Astro 中间件

任何 Astro 中间件都会在构建时应用于预渲染页面，在运行时应用于按需渲染页面。

要在预渲染页面上实现重定向、访问控制或自定义响应头，请通过启用 [`edgeMiddleware` 选项](/zh-cn/reference/adapter-reference/#edgemiddleware) 在 Netlify Edge Functions 上运行你的中间件：

```js title="astro.config.mjs" ins={8}
import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
  // ...
  output: 'server',
  adapter: netlify({
    edgeMiddleware: true,
  }),
});
```

当 `edgeMiddleware` 启用时，边缘函数将为所有请求执行你的中间件代码，包括静态资产、预渲染页面和按需渲染页面。

对于按需渲染的页面，`context.locals` 对象会被 JSON 序列化并通过标头发送给无服务器函数，由该函数执行渲染。作为安全措施，除非请求来自生成的边缘函数，否则无服务器函数将拒绝服务，并返回 `403 Forbidden` 响应。

### Netlify 图片 CDN 支持

这个适配器默认使用 [Netlify 图片 CDN](https://docs.netlify.com/image-cdn/overview/) 来实时转换图片，因而不会影响构建时间。
它背后是使用 [Astro 图片服务](/zh-cn/reference/image-service-reference/) 实现的。

如果你想退出 Netlify 的图片 CDN 远程图片优化，可以使用 `imageCDN` 选项：

```js title="astro.config.mjs" ins={8}
import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
  // ...
  output: 'server',
  adapter: netlify({
    imageCDN: false,
  }),
});
```
如果你使用的图片托管在另一个域名上，你必须使用 [`image.domains`](/zh-cn/reference/configuration-reference/#imagedomains) 或 [`image.remotePatterns`](/zh-cn/reference/configuration-reference/#imageremotepatterns) 配置选项授权该域名或 URL 模式：

```js title="astro.config.mjs" ins={8-10}
import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
    // ...
    output: 'server',
    adapter: netlify(),
    image: {
      domains: ['example.com'],
    },
});
```
要了解更多信息，请参阅[授权远程图片的指南](/zh-cn/guides/images/#授权远程图像)。如果图片托管在与你的站点相同的域名上，这不是必需的。

### 使用 Netlify 适配器的静态站点

对于托管在 Netlify 上的静态站点（`output: 'static'`），你通常不需要适配器。然而，某些部署功能只能通过适配器来实现。

静态站点需要安装这个适配器来使用和配置 Netlify 的[图像服务](#netlify-图片-cdn-支持)。

如果你在 Astro 配置中使用了 `redirects` 配置，Netlify 适配器可以将其转换为正确的 `_redirects` 格式。

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify/static';

export default defineConfig({
  // ...
  adapter: netlify(),
  redirects: {
    '/blog/old-post': '/blog/new-post',
  },
});
```

一旦你运行了 `astro build`，就会有一个 `dist/_redirects` 文件。Netlify 将使用它来正确地路由生产环境中的页面。

:::note
你仍然可以包含一个 `public/_redirects` 文件来手动重定向。你在重定向配置中指定的任何重定向都会被追加到你自己的重定向的末尾。
:::

### 缓存页面

可以缓存没有任何动态内容的按需渲染页面，以提高性能并降低资源使用率。
在适配器中启用 `cacheOnDemandPages` 选项将会缓存所有服务器渲染的页面，最长可达一年：

```ts title="astro.config.mjs"
export default defineConfig({
  // ...
  output: 'server',
  adapter: netlify({
    cacheOnDemandPages: true,
  }),
});
```

这可以通过向你的响应添加缓存头来根据每个页面进行更改：
```astro title="pages/index.astro"
---
import Layout from '../components/Layout.astro';

Astro.response.headers.set('CDN-Cache-Control', 'public, max-age=45, must-revalidate');
---

<Layout title="Astro on Netlify">
  {new Date()}
</Layout>
```

使用[细粒度缓存控制](https://www.netlify.com/blog/swr-and-fine-grained-cache-control/)，Netlify 支持标准缓存头，例如 `CDN-Cache-Control` 或 `Vary`。
请参阅文档，了解如何实现例如 TTL 或 SWR 缓存：https://docs.netlify.com/platform/caching

## 示例

* [Astro Netlify Edge Starter](https://github.com/sarahetter/astro-netlify-edge-starter) 提供了一个示例以及 README 中的指南。
* [浏览 GitHub 上的 Astro Netlify 项目](https://github.com/search?q=path%3A**%2Fastro.config.mjs+%40astrojs%2Fnetlify\&type=code) 查看更多示例！

[astro-integration]: /zh-cn/guides/integrations-guide/
